Version: 2.0

Inbound Message

An inbound message or MO(Mobile Originated) message is a message sent to businesses from a WhatsApp user.

The default format for inbound message is as mentioned below:

Inbound message fields

Name	Description	JSON Type
from	MSISDN of the user sending the message.	String
to	The identifier of the receiving bot.	String
replying_to	A context object, present only if the user is replying to a specific thread.	String
id	Generated message id for the inbound message.	String
timestamp	ISO-8601 datetime of the status update.	String
referral	Containing details about Click to WhatsApp Ads from Meta.	Object
context	Used when user replies or interacts with one of the message.	Object
type	The type of message sent by user. Like - text, image, video, audio, document, interactive, button, location, order.	Text

The following are different types of inbound messages sent by user:

Location
Quick Reply Button
Interactive Message
List Message
Quick Reply Message
Media Message
Image
Video
Document
Audio
Message generated from Click to WhatsApp Ads
Inbound Replies to Sent messages

Text message

Name	Description	JSON Type
body	The text of the text message.	String

Payload:

{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16315551234"
        }
    ],
    "messages": [
        {
            "from": "16315551234",
            "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
            "timestamp": "1518694235",
            "text": {
                "body": "Hello this is an answer"
            },
            "type": "text"
        }
    ]
}

Image Message

Name	Description	JSON Type
mime_type	Supported data type of the image.	String
caption	Caption value provided by the user - Optional.	String
url	Image URL to download the file.	String

Payload:

{
    "messages": {
        "image": {
            "mime_type": "image/jpeg",
            "caption": null,
            "url": "https://sX.ap-south-X.amazonaws.com/whatsapp"
        },
        "referral": null,
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXdXAgo-sXXXXMFkeHXH",
        "to": "9XXXXXXXXXXX",
        "type": "image",
        "timestamp": 1598360619
    }
}

Document Message

Name	Description	JSON Type
mime_type	Supported data type.	String
caption	Caption value provided by the user - Optional.	String
url	Document URL to download the file.	String

Payload:

{
    "messages": {
        "referral": null,
        "document": {
            "mime_type": "application/pdf",
            "caption": "doc_name.pdf",
            "url": "https://sX.ap-south-X.amazonaws.com/whatsapp"
        },
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXdXAgo-sXXXXXAO6XVR",
        "to": "9XXXXXXXXXXX",
        "type": "document",
        "timestamp": 1598360619
    }
}

Zip File Message
Payload

{
    "messages": {
        "referral": null,
        "document": {
            "mime_type": "application/zip",
            "caption": "",
            "url": "https: //sX.ap-south-X.amazonaws.com/whatsapp",
            "filename": "10mb.zip",
            "sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120"
        },
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXdXAgo-sXXXXXAO6XVR",
        "to": "9XXXXXXXXXXX",
        "type": "document",
        "timestamp": 1598360619
    }
}

Media Content in 'base64' for Outbound Reply:
Payload

{
    "messages": [
        {
            "sender": "9180XXXXXXXX",
            "to": "9178XXXXXXXX",
            "messageId": "fghgvd8f5XXXXfsf23",
            "transactionId": "dsXXXXXfadgdfhh69665fd6",
            "channel": "wa",
            "type": "media",
            "media": {
                "contentType": "application/pdf",
                "sha256Hash": "",
                "caption": "hello",
                "mediaUrl": "",
                "content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovV"
            }
        }
    ],
    "responseType": "json"
}

Audio Message

Name	Description	JSON Type
mime_type	Supported data type.	String
caption	Caption value provided by the user - Optional.	String
url	Audio URL to download the file.	String

Payload:

{
    "messages": {
        "voice": {
            "mime_type": "audio/ogg; codecs=opus",
            "url": "https://sX.ap-south-X.amazonaws.com/whatsapp"
        },
        "referral": null,
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXdXAhBGtmCj_XXXXNDzynTHUCZc",
        "to": "9XXXXXXXXXXX",
        "type": "voice",
        "timestamp": 1598360619
    }
}

Video Message

Name	Description	JSON Type
mime_type	Supported data type.	String
Caption	Caption value provided by the user - Optional.	String
Url	Video URL to download the file.	String

Payload:

{
    "messages": {
        "referral": null,
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXXXXgo-XXXXlXMibgcy",
        "video": {
            "mime_type": "video/mpX",
            "url": "https://sX.ap-south-X.amazonaws.com/whatsapp"
        },
        "to": "9XXXXXXXXXXX",
        "type": "video",
        "timestamp": 1598360619
    }
}

Location Message

Name	Description	JSON Type
type	Fixed value location.	String
latitude	Latitude of location being sent.	Number
longitude	Longitude of location being sent.	Number
address	Address of the location.	String
name	Name of the location.	String
url	URL for the website where the user downloaded the location information.	Object

Payload:

{
    "messages": {
        "button": {
            "payload": "21323",
            "text": "Buy"
        },
        "referral": null,
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZmZJXVFAgoXLV5XRRXOODZk",
        "to": "9XXXXXXXXXXX",
        "type": "button",
        "timestamp": 1598360619
    }
}

Quick Reply Button Message
This is the reply from a template 'quick-reply' button message. Don't confuse with the reply from an interactive button message.

Name	Description	JSON Type
type	Fixed value button.	String
text	The button text.	String
payload	The payload that was sent with the button.	String

Payload:

{
  "messages": [
    {
      "button": {
        "payload": "21323",
        "text": "Buy"
      },
      "referral": null,
      "from": "9XXXXXXXXXXX",
      "id": "ABEGkZmZJXVFAgoXLV5XRRXOODZk",
      "to": "9XXXXXXXXXXX",
      "type": "button",
      "timestamp": 1598360619
    },
    {
      "button": {
        "payload": "21323",
        "text": "Buy"
      },
      "referral": null,
      "from": "9XXXXXXXXXXX",
      "id": "ABEGkZmZJXVFAgoXLV5XRRXOODZk",
      "to": "9XXXXXXXXXXX",
      "type": "button",
      "timestamp": 1598360619
    }
  ]
}

Interactive Messages
Reply to non-templated list/button messages.

Name	Description	JSON Type
type	Fixed value interactive.	String
list_reply	Used to notify you when customers are replying to List Messages. Contains the following information about the rows selected by the customer: id, title and description.	String
Button_reply	Used to notify you when customers are replying to Quick Reply Messages. Contains the following information about the button clicked by the customer: id and title.	String
Button	Title of the button - for both list/button message.	String
buttonUniqueID	Unique button identifier.	String

Button Reply
Payload

{
    "messages": {
        "button": "Test QR Buttons",
        "referral": null,
        "interactive": {
            "list_reply": null,
            "type": "button_reply",
            "button_reply": {
                "id": "id-X",
                "title": "Test QR Buttons"
            }
        },
        "buttonUniqueID": "id-X",
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXXXXgo-sKqZydjc3XfX",
        "to": "9XXXXXXXXXXX",
        "type": "interactive",
        "timestamp": 1598360619
    }
}

List Reply
Payload

{
    "messages": {
        "button": "row-title-content",
        "referral": null,
        "interactive": {
            "list_reply": {
                "description": "",
                "id": "idX",
                "title": "row-title-content"
            },
            "type": "list_reply",
            "button_reply": null
        },
        "buttonUniqueID": "idX",
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXdXAgo-sXXXX_gWfQdV",
        "to": "9XXXXXXXXXXX",
        "type": "interactive",
        "timestamp": 1598360619
    }
}

Click to WhatsApp Ads Messages
Referral: This object is included in notifications when a user clicks on an ad, that clicks to WhatsApp and sends a message to the business. This is how the referral property works:

A user clicks on an ad with the Click to WhatsApp call-to-action.
User is redirected to WhatsApp and sends a message to the advertising business.
User sends a message to the business. Be aware that users may elect to remove their referral data.
The advertising business gets an inbound message notification including the referral property, which provides additional context on the ad that triggered the message. Knowing all this information, the business can appropriately reply to the user message.

Name	Description	JSON Type
headline	Headline used in the ad that generated the message.	String
body	Body from the ad that generated the message.	String
source_type	The type of the ad’s source. Currently, supported values are ad and post.	String
source_id	Facebook ID for an ad or a post.	String
source_url	The url that leads to the ad or post.	String
image & video	The image or video that the user saw and clicked.	Object

Payload

{
  "messages": [
    {
      "text": {
        "body": "hellosinch"
      },
      "referral": {
        "headline": "Our new product",
        "body": "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>",
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45"
        }
      },
      "from": "9XXXXXXXXXXX",
      "id": "ABEGkZZngXdXAgo-sXXXX_gWfQdV",
      "to": "9XXXXXXXXXXX",
      "type": "text",
      "timestamp": 1598360619
    },
    {
      "text": {
        "body": "hellosinch"
      },
      "referral": {
        "headline": "Our new product",
        "body": "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>",
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45"
        }
      },
      "from": "9XXXXXXXXXXX",
      "id": "ABEGkZZngXdXAgo-sXXXX_gWfQdV",
      "to": "9XXXXXXXXXXX",
      "type": "text",
      "timestamp": 1598360619
    }
  ]
}

Inbound Reply to Sent Messages
Users can respond to a specific message in WhatsApp. For the business to understand the context of a message reply, we include the context object. This context object provides the 'id' of the message to which the customer has replied.

Context: This object (namely replying_to) is included in the MO notification if it is in reply to a message. It contains information about the original message.

Name	Description	JSON Type
id	Message ID of the message which is being replied directly to.	String
from	MSISDN of the user which sent the message with the above message id.	String
referred_product	Used for enquiries coming from a Product Detail Page, Single Product Messages and Multi-Product Message.	Object

Case: Customer Replied to Your Message
Payload

{
  "messages": [
    {
      "text": {
        "body": "hellosinch"
      },
      "context": {
        "from": "9XXXXXXXXXXX",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf"
      },
      "from": "9XXXXXXXXXXX",
      "id": "ABEGkZZngXdXAgo-sXXXX_gWfQdV",
      "to": "9XXXXXXXXXXX",
      "type": "text",
      "timestamp": 1598360619
    },
    {
      "text": {
        "body": "hellosinch"
      },
      "context": {
        "from": "9XXXXXXXXXXX",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf"
      },
      "from": "9XXXXXXXXXXX",
      "id": "ABEGkZZngXdXAgo-sXXXX_gWfQdV",
      "to": "9XXXXXXXXXXX",
      "type": "text",
      "timestamp": 1598360619
    }
  ]
}

Case: Customer asking for information about a specific product
Payload

{
    "messages": {
        "text": {
            "body": "hellosinch"
        },
        "context": {
            "referred_product": {
                "catalog_id": "catalog-ID",
                "product_retailer_id": "product-ID"
            }
        },
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZZngXdXAgo-sXXXX_gWfQdV",
        "to": "9XXXXXXXXXXX",
        "type": "text",
        "timestamp": 1598360619
    }
}

Order Message
Case: Customer placed an order after receiving a Multi or Single Product Message
Payload

{
    "messages": {
        "from": "9XXXXXXXXXXX",
        "id": "ABEGkZmZJXVFAgoXLV5XRRXOODZk",
        "to": "9XXXXXXXXXXX",
        "type": "order",
        "order": {
            "catalog_id": "catalog_id",
            "product_items": [
                {
                    "product_retailer_id": "product-ID",
                    "quantity": "number-of-items",
                    "item_price": "unitary-price-of-item",
                    "currency": "price-currency"
                }
            ],
            "text": "text-message-sent-along-with-the-order"
        }
    }
}